Transmisión de datos

Los servicios web se usan para enviar datos de transacción entre el sistema host y Vocollect VoiceCheck. VoiceCheck admite servicios web SOAP y REST. Estos servicios proporcionan la funcionalidad de importación y exportación para el sistema VoiceCheck.

Los formatos de mensaje y servicios se describen detalladamente a continuación y el XML de referencia para el lenguaje de descripción de servicios web (WSDL) SOAP y el lenguaje de descripción de aplicaciones web (WADL) REST se proporcionan en el paquete de producto. Antes, se podían ver las descripciones de los servicios si ingresaba http://<host>:<port>/VoiceCheck/services/api/swagger.json en su navegador web. Este vínculo reemplaza el vínculo usado anteriormente http://<host>:<port>/VoiceCheck/services.

Flujo de mensajes de servicios web

Configuración y seguridad

Todas las comunicaciones se realizan a través de HTTP o HTTPS, según la configuración de VoiceCheck.

Para la importación de datos, todos los servicios web SOAP que proporciona VoiceCheck requieren autenticación con WS-Security UsernameToken. Todos los servicios web REST para importación requieren autenticación mediante el uso de autenticación HTTP básica.

VoiceCheck posee una función de acceso que se puede configurar en la interfaz de usuario y que determina los permisos que tiene un usuario para ejecutar los servicios web. Los clientes del servicio web del sistema host deben estar configurados para autenticarse con los servicios web de VoiceCheck como un usuario con esta función.

Para la exportación de datos, VoiceCheck admite el uso de autenticación HTTP básica para acceder a un servicio SOAP o REST en el sistema host. La autenticación es opcional, pero si se usa, se configura en VoiceCheck y la contraseña se cifra y almacena en la base de datos de VoiceCheck.

VoiceCheck también proporciona un método para configurar la URL del punto final del servicio para los servicios que proporciona el sistema host. Esta URL de punto final es una configuración obligatoria en la IGU.

Existe solo un nombre de usuario y contraseña que se usa para consumir todos los servicios que el sistema host expone para VoiceCheck. Actualmente, solo se expone un servicio para que VoiceCheck publique los resultados de la asignación en el sistema host.

La información de la configuración (punto final del servicio, tipo de cliente del servicio web, nombre de usuario y contraseña) se establece a nivel de sistema en VoiceCheck. Estas configuraciones se pueden encontrar en la página Administración > Configuración del sistema. La configuración supone que la única instancia de VoiceCheck se conectará con un único punto final del sistema host.

Espacios de nombres y esquemas XML

VoiceCheck declara un espacio de nombre para todos los elementos XML que se usan en los servicios SOAP y REST, con la excepción del elemento faultInfo (consulte la siguiente nota). El espacio de nombre es:

http://service.web.voicecheck.vocollect.com/

Para servicios SOAP que proporciona VoiceCheck para importación de datos, puede encontrar el espacio de nombre y esquema en WSDL.

Para servicios REST que proporciona VoiceCheck para importación de datos, puede encontrar el espacio de nombre y esquema en WADL. Tenga en cuenta que para el servicio web Crear asignación, los clientes de REST no tiene que calificar el XML con el espacio de nombre, sin embargo, esto se recomienda encarecidamente.

En caso del servicio REST que consume VoiceCheck para publicar los resultados de la asignación en un sistema host, en el ejemplo de WADL que se proporciona en el paquete de producto se define el esquema y espacio de nombre que el servidor espera ver en el XML.

El elemento faultInfo no se define como parte de un espacio de nombre. En el caso de los servicios REST, VoiceCheck no califica el elemento con un espacio de nombre cuando lo envía en una respuesta de error a un sistema host. De manera similar, el sistema host no debe calificar un elemento con un espacio de nombre en una respuesta para VoiceCheck.

Manejo de fallas de datos de asignación

Manejo de fallas REST

Si hay fallas, se pueden devolver varios códigos de estado HTTP según la falla y dónde ocurrió esta durante el proceso. VoiceCheck usa el marco Apache^® XF para procesar las solicitudes de servicios web y el marco puede devolver errores durante su procesamiento, tales como 406 – No aceptable o 415 – Tipo de medio no compatible, antes de llegar a la lógica de negocios de VoiceCheck.

Los errores provenientes de la lógica de negocios de VoiceCheck solo tienen dos códigos de estado:

• 400 – Solicitud incorrecta: El cliente infringió una restricción o regla de negocio (normalmente datos incorrectos). Si se envía nuevamente el mensaje sin realizar cambios en el contenido se producirá el mismo error.
• 500 – Error interno del servidor: Hubo un error interno del servidor durante el procesamiento de la solicitud. Volver a intentar el mensaje PUEDE dar resultados correctos.

Asimismo, los errores provenientes de la lógica de negocios de VoiceCheck incluyen un elemento XML faultInfo que contiene información adicional acerca del error que ocurrió. Las propiedades del elemento faultInfo se muestran a continuación:

Manejo de fallas SOAP

Las fallas SOAP 1.1 se devuelven para todos los errores. Todas las fallas contienen un código de falla y una cadena de falla de acuerdo a lo especificado en SOAP 1.1. Los dos códigos de falla principales de SOAP 1.1, Cliente y Servidor, se especifican para la mayoría de las fallas. VoiceCheck generalmente usa estos códigos en la manera como se describe en la especificación de SOAP 1.1.

Existen errores que ocurren durante la autenticación que usan los códigos de falla especificados en WS-Security (seguridad de servicios web). Las implementaciones y API de los servicios web Java pueden devolver otros códigos de falla.

Aunque no es posible enumerar todos los códigos de falla que pueden ocurrir, existen reglas generales que pueden permitir el que los clientes de los servicios web realicen un manejo de fallas consistente:

• Los códigos de falla distintos a Servidor, por lo general indican que no tiene sentido reenviar automáticamente el mensaje. Estos se envían cuando el cliente hizo algo incorrecto antes de la transmisión que llega a la lógica de aplicación en el servidor, como por ejemplo, fallas de autenticación o mensajes formados incorrectamente.
• Cuando el código de falla es Servidor, si la falla proviene de la lógica del servidor de aplicaciones, incluirá el elemento de detalle de falla de SOAP 1.1. El formato se especifica en el WSDL, pero contiene la información que se indica a continuación.

Elemento de información de falla

Los servicios web REST y SOAP incluyen la misma información de error cuando la falla proviene de la lógica del servidor de aplicaciones de VoiceCheck.

Se debe usar la implementación REST del servidor host para publicar los resultados de la asignación para mostrar el mensaje de error en la IGU de VoiceCheck, de lo contrario, el usuario ve un mensaje genérico.

Propiedad	Tipo	Definición
errorCode	long	Código numérico que representa el error. Valores válidos: 3000 = Error interno del servidor (la solicitud puede o no realizarse correctamente en el reintento) 3001 = Solicitud incorrecta (no se recomienda el reintento de solicitud automatizado)
message	cadena	Mensaje en lenguaje natural que explica el error.